home *** CD-ROM | disk | FTP | other *** search
/ Aminet 23 / Aminet 23 (1998)(GTI - Schatztruhe)[!][Feb 1998].iso / Aminet / util / misc / TeeHandler.lha / TeeHandler.doc < prev    next >
Encoding:
Text File  |  1997-12-18  |  6.1 KB  |  165 lines
  1. TABLE OF CONTENTS
  2.  
  3. tee-handler/tee_handler
  4. tee-handler/tee_handler                               tee-handler/tee_handler
  5.  
  6.    NAME
  7.        tee_handler -- Writes input to several outputs and StdOut. (V36)
  8.  
  9.    SYNOPSIS
  10.        Open("TEE:[FileName_One][,FileName_Two][,...]");
  11.  
  12.    FUNCTION
  13.        
  14.        Background
  15.        ----------
  16.        In the UNIX environment, the output of a command can be displayed 
  17.        both on the terminal and saved to a file by using the command 
  18.        'tee' and pipes:
  19.        
  20.            $ who | tee /users/log/970924_1300
  21.        
  22.        Even if there was a standard 'tee' utility available for the
  23.        Amiga, it would be effectively useless with the standard Shell
  24.        because AmigaShell lacks the pipe function.  It could be 
  25.        simulated by saving the output and then 'type'ing it:
  26.        
  27.            1.Work:> Dir >Work:SysList/970924 SYS: ALL
  28.            1.Work:> Type Work:SysList/970924
  29.        
  30.        But this uses two command lines, and what if you need monitor
  31.        the output while it's being saved?  There is the PIPE: handler,
  32.        and you could try this:
  33.        
  34.            1.Work:> Dir >PIPE:blabla SYS: ALL
  35.            2.Work:> tee <PIPE:blabla Work:SysList/970924
  36.        
  37.        But, once again, this uses two commands, and these are on two
  38.        different Shells!  And while there are shells with pipes
  39.        (eg CShell, ZShell etc.), most either use PIPE: with one Shell,
  40.        requiring the whole output to be read first, or save the output
  41.        to a temporary file, which is also pretty inefficient if you're
  42.        going to be saving the file anyway.
  43.        
  44.        The Tee-Handler
  45.        ---------------
  46.        TeeHandler was written to overcome these limitations.  With it, you
  47.        can write the standard output of any command to both the Shell and
  48.        to zero or more output files.  Any type of output file can be 
  49.        specified, including DOS Devices like PRT:, SER:, PIPE: etc.  The
  50.        output is immediate, you don't have to wait for the whole output
  51.        to be generated before you see it.
  52.        
  53.        TeeHandler is implemented as a DOS Device.  The standard name
  54.        is "TEE:", followed by a list of filenames seperated by commas,
  55.        eg:
  56.        
  57.            1.Work:> Dir >TEE:One,Two,Three
  58.        
  59.        If you need to include a comma in you're filename, you can 'escape'
  60.        it with the backslash (\). so that eg:
  61.        
  62.            1.Work:> Dir >TEE:One\,Two
  63.        
  64.        Would produce a file in the current directory called "One,Two".  
  65.        Any character preceded by a backslash will be 'escaped', so you
  66.        can use '\\' to get one '\' in your filename.
  67.        
  68.        NOTE: If you need to use the character '^' as the first character
  69.              in your filename, please 'escape' it with '\^'.  Although
  70.              it isn't yet implememted, I will be using this character in
  71.              future versions to provide options to the handler about what
  72.              to do with this file.
  73.        
  74.        You can append the output to your output files be using the
  75.        double redirection '>>' eg:
  76.        
  77.            1.Work:> Dir >>TEE:One,Two,Three
  78.        
  79.        This will open three files in Read/Write mode and Seek them to the 
  80.        end (this is done by the Shell, but handled by TEE).
  81.        
  82.        You may specify no files, in which case the output is redirected
  83.        only to the StdOut.  Invalid filenames (ie those that cause 
  84.        Open() to return NULL) and empty filenames are ignored.
  85.        
  86.        Note that you may use colons (:) and forward-slashes (/) as normal
  87.        in your filenames.
  88.  
  89.    INPUTS
  90.        FileName_One - Name of first output file.
  91.        
  92.        FileName_Two - Name of second output file, etc
  93.  
  94.    PACKETS
  95.        ACTION_FINDUPDATE
  96.        ACTION_FINDOUTPUT
  97.        ACTION_SEEK
  98.        ACTION_WRITE
  99.        ACTION_END
  100.        ACTION_IS_FILESYSTEM
  101.  
  102.    MOUNTLIST ENTRY
  103.        This is the default mountlist entry used for tee-handler:
  104.        
  105.           TEE:    Handler   = L:tee-handler
  106.                   Priority  = 0
  107.                   Stacksize = 4096
  108.                   GlobVec   = -1
  109.           #
  110.  
  111.    EXAMPLES
  112.        List directory to both the Shell and a single file:
  113.            Dir >TEE:Filename
  114.        
  115.        List directory to the Shell and several files:
  116.            Dir >TEE:Filename1,Filename2,Filename3
  117.        
  118.        List directory to the Shell and append it to several files:
  119.            Dir >>TEE:Filename1,Filename2,Filename3
  120.        
  121.        Copy a file to both the Shell and several other files:
  122.            Copy S:Startup-Sequence TEE:Filename1,Filename2,Filename3
  123.        
  124.        Copy a file to both the Shell, the printer and a serial terminal:
  125.            Copy S:Startup-Sequence TEE:PRT:,SER:
  126.        
  127.        List directory to the Shell and a file with commas in the filename:
  128.            Dir >TEE:File\,Name\,With\,Commas
  129.        
  130.        List directory to the Shell and a file with spaces in the filename:
  131.            Dir >"TEE:File Name With Spaces"
  132.        
  133.        List directory to the Shell and append files with spaces and commas:
  134.            Dir >>"TEE:One,Two,Three Four,Five\,Six"
  135.    
  136.    HISTORY
  137.        v1.39 (21st Oct 1997)
  138.            Initial Release
  139.        
  140.        v1.40 (17th December 1997)
  141.            Fixed a problem with buffering.  In the previous release, 
  142.            AmigaDOS viewed TEE: as a normal file and buffered the
  143.            output.  This resulted in jerky and disjointed `spurts' of
  144.            output.  In this version, TEE: is recognised as an interactive
  145.            stream (like a console), and the output is written at the end
  146.            of each line.  For those that are interested, this was achieved
  147.            by setting the FileHandle's fh_Port field to DOSTRUE (-1L) 
  148.            instead of NULL.
  149.    
  150.    BUGS
  151.        TeeHandler will freeze if asked to output to itself, eg
  152.            Dir >TEE:TEE:...
  153.    
  154.    AUTHOR
  155.        The author of this handler is Karl J. Ots.  You can contact me via
  156.        my e-mail address:
  157.        
  158.            kjots@gem.menzies.latrobe.edu.au
  159.        
  160.        And visit my web page:
  161.        
  162.            http://gem.menzies.latrobe.edu.au/~kjots
  163.        
  164.        All my software is available from my web page.
  165.